Release 10.1A: OpenEdge Development:
Programming Interfaces

Reading and writing data

Once you have initialized a MEMPTR variable, you can build a data aggregate (structure) or access an existing structure in the associated memory region using several memory-writing statements and memory-reading functions. Memory-writing statements write values to specified locations in the memory region. Memory-reading functions return values from the specified locations in the memory region. Through an appropriate choice of these statements and functions you can thus copy Progress data types and bit fields to and from MEMPTR variables. You can also copy complete Progress database records to and from MEMPTR variables.

Note: Before setting or getting values in a MEMPTR variable, you might want to check the MEMPTR size using the GET-SIZE function. For more information, see the "Initializing and uninitializing MEMPTR variables" section.

This is the syntax for the MEMPTR memory-writing statements (except PUT-STRING):

Syntax

PUT-datatype ( mptr-name , byte-position ) = expression

This is the syntax for the MEMPTR memory-reading functions (except GET-STRING and GET-BYTES):

Syntax

GET-datatype ( mptr-name , byte-position )

Each PUT-datatype statement writes a value (expression) of a certain data type to the memory region associated with the MEMPTR variable mptr-name at the specified byte-position. Each GET-datatype function reads and returns the value of a data type from the memory region associated with the MEMPTR variable mptr-name at the specified byte-position. The byte-position in these statements and functions is specified by an integer expression that starts at one (1).

The PUT-STRING statement and GET-STRING function each allow an additional optional parameter that specifies the number of bytes to write or read in the MEMPTR variable. The GET BYTES function has the same parameter, but it is required for this function.

Note: The mptr-name parameter in these statements and functions can reference RAW as well as MEMPTR variables. However, the EPIs that require MEMPTR variables cannot use RAW variables directly. You must convert RAW values to MEMPTR before using them with these EPIs. You can do this using direct assignment between RAW and MEMPTR variables or by using statements and functions such as PUT-BYTES, GET-BYTES, or GET-RAW.

Memory-writing statements

Progress provides the PUT-datatype statements shown in Table 8–1.

Table 8–1: PUT-datatype statements 

Statement	Description
PUT-BYTE	Writes an integer value to the specified 1-byte location.
PUT-SHORT	Writes an integer value to the specified 2-byte location.
PUT-UNSIGNED-SHORT	Writes an unsigned integer value to the specified 2-byte location.
PUT-LONG	Writes an integer value to the specified 4-byte location.
PUT-FLOAT	Writes a decimal value to the specified 4-byte location as a single-precision floating-point value.
PUT-DOUBLE	Writes a decimal value to the specified 8-byte location as a double-precision floating-point value.
PUT-STRING	Writes a character string value to the specified location, either null terminated or for a specified number of bytes.
PUT-BYTES	Writes the contents of a RAW or MEMPTR variable to the specified byte location of a RAW or MEMPTR variable.

For more information on these statements, see the OpenEdge Development: Progress 4GL Reference .

Memory-reading functions

Progress provides the GET-datatype functions shown in Table 8–2.

Table 8–2: GET-datatype functions 

Function	Description
GET-BYTE	Returns the integer value of the specified 1-byte location.
GET-SHORT	Returns the integer value of the specified 2-byte location.
GET-UNSIGNED-SHORT	Returns the value of the specified 2-byte location, interpreted as an unsigned integer.
GET-LONG	Returns the integer value of the specified 4-byte location.
GET-FLOAT	Returns the decimal value of the specified 4-byte location, interpreted as a single-precision floating-point value.
GET-DOUBLE	Returns the decimal value of the specified 8-byte location, interpreted as a double-precision floating-point value.
GET-STRING	Returns the character string value from the specified location, either null terminated or for a specified number of bytes that can include nulls.
GET-BYTES	Returns, as a MEMPTR or RAW value, the specified number of bytes from the specified byte location of a RAW or MEMPTR variable.

For more information on these functions, see the OpenEdge Development: Progress 4GL Reference .

Copying between basic Progress data types and MEMPTR

Table 8–3 lists the basic Progress data types and how you can copy them in and out of a MEMPTR variable.

Table 8–3: Copying between basic Progress data types
and MEMPTR

Data type	Copying to/from MEMPTR
DATE	To copy into a MEMPTR: Use INTEGER(date-expression) to obtain an integer value. Use the PUT-LONG statement to copy integer value to MEMPTR. To copy from a MEMPTR: Use the GET-LONG function to return the integer value. Use the DATE(integer-expression) function to return the date.
DECIMAL1	To copy into a MEMPTR: Use the PUT-DOUBLE or PUT-FLOAT statement. To copy from a MEMPTR: Use the GET-DOUBLE or GET-FLOAT function.
INTEGER1	To copy into a MEMPTR: Use the PUT-LONG, PUT-SHORT, PUT-UNSIGNED-SHORT, or PUT-BYTE statements. To copy from a MEMPTR: Use the GET-LONG, GET-SHORT, GET-UNSIGNED-SHORT, or GET-BYTE functions.
LOGICAL1	To copy into a MEMPTR: Use the PUT-LONG, PUT-SHORT, PUT-UNSIGNED-SHORT, or PUT-BYTE statements. To copy from a MEMPTR: Use the GET-LONG, GET-SHORT, GET-UNSIGNED-SHORT, or GET-BYTE functions.
RAW	To copy into a MEMPTR: Assign the RAW value directly using an assignment statement or use the PUT-RAW statement. To copy from a MEMPTR: Assign the MEMPTR value directly using an assignment statement or use the GET-RAW function.

1The choice of exact statement or function to use depends on the data type used by the shared library routine or the socket application with your application is communicating.

Manipulating bit values

You can copy bit values up to the size of a Progress INTEGER from one INTEGER value to another. The statement to copy bit values to an INTEGER variable, PUT-BITS, has the following syntax:

Syntax

PUT-BITS( destination , start-position , count ) = integer-expression

This statement interprets an integer (integer-expression) as the sequence of bits representing the binary value of integer-expression. For example, if the value of integer-expression is 22, the bit sequence is 10110. The statement interprets the INTEGER variable, destination, as a sequence of bits and writes the sequence of bits from integer-expression into destination, starting at the specified bit position (start-position) The bit position in destination is counted from the low-order bit, where the first bit is bit one (1). If the value of integer-expression is too large to store in the specified number of bits, Progress stores the low-order count bits of integer-expression in the specified count bits within destination.

The function to return some number of bits from an INTEGER variable, GET-BITS, has the following syntax:

Syntax

GET-BITS( source , start-position , count )

This function returns the INTEGER that represents the value of the number of bits specified by count starting at the specified low-order bit position (start-position) within the INTEGER variable specified by source.

Thus, you can store bit values in MEMPTR variables and return bit values from MEMPTR variables by using the PUT-LONG statement and GET-LONG function to store and return the corresponding INTEGER expression that contains the bit pattern.

Copying between database records and MEMPTR

Copying a database record to and from a MEMPTR variable relies on the RAW-TRANSFER statement. This statement allows you to copy a whole database record buffer to a RAW variable or to copy a RAW variable to a database record buffer.

To store a database record in a MEMPTR variable:

Copy the record buffer to a RAW variable using the RAW-TRANSFER statement.
Assign the RAW variable to the MEMPTR variable or to the specified position in the MEMPTR variable using the PUT-BYTES statement.

To retrieve a database record from a MEMPTR variable:

Assign the MEMPTR variable to a RAW variable or use the GET-BYTES function to copy the specified bytes from the MEMPTR to the RAW variable.
Copy the RAW variable to the record buffer using the RAW-TRANSFER statement.